Inside Macintosh: QuickTime
The Movie Toolbox provides a number of functions that allow your application to examine result codes generated by toolbox functions. In addition, the Movie Toolbox allows your application to provide a function that performs custom error notification. This section discusses these error functions.
Important
The Movie Toolbox introduces an additional error-reporting mechanism. In addition to returning errors as function results, the Movie Toolbox functions return error indications to calling applications by setting one of two values that are private to the Movie Toolbox: a current error value or a sticky error value. Your application can retrieve these values by calling the
GetMoviesError
or
GetMoviesStickyError
functions described in this section. To let you know whether there is an error indication, the heading "ERROR CODES" may appear with the entry "None" in function descriptions throughout this chapter.
The Movie Toolbox maintains two error values for your application: the current error and the sticky error. The current error value contains the result code from the last Movie Toolbox function. The toolbox updates the current error value each time your application calls a Movie Toolbox function. Your application may call the GetMoviesError function to obtain the current error value after calling any Movie Toolbox function. Many Movie Toolbox functions do not return an error as a function result--you must use the GetMoviesError function to obtain the result code. Even if a function explicitly returns an error as a function result, that result is also available using the GetMoviesError function.
The Movie Toolbox saves a result code in the sticky error value. Your application clears the sticky error value by calling the ClearMoviesStickyError function. The Movie Toolbox then places the first nonzero result code from any toolbox function used by your application into the sticky error value. The Movie Toolbox does not replace the value in the sticky error value until your application clears the value again. Your application uses the GetMoviesStickyError function to obtain the result code stored in the sticky error value. In this manner, you can preserve and retrieve important result code information.
Your application uses the SetMoviesErrorProc function to designate an error function. The Movie Toolbox calls this error function each time there is an error.
The GetMoviesError function returns the contents of the current error value and resets the current error value to 0.
pascal OSErr GetMoviesError (void);
The current error value contains the result code from the previous Movie Toolbox function. Most Movie Toolbox functions do not return an error as a function result--you must use the GetMoviesError function to obtain the result code. Even if a function explicitly returns an error as a function result, that result is also available using the GetMoviesError function.
The GetMoviesStickyError function returns the contents of the sticky error value. The sticky error value contains the first nonzero result code from any Movie Toolbox function that you called after having cleared the sticky error with the ClearMoviesStickyError function.
pascal OSErr GetMoviesStickyError (void);
The ClearMoviesStickyError function clears the sticky error value .
pascal void ClearMoviesStickyError (void);
The Movie Toolbox allows applications to perform custom error notification. Your application must identify its custom error-notification function to the Movie Toolbox. The SetMoviesErrorProc function allows you to identify your application's error-notification function. Error-notification functions can be especially useful when you are debugging your program.
pascal void SetMoviesErrorProc (MoviesErrorUPP errProc,
long refcon);
pascal void MyErrProc (OSErr theErr, long refCon);
Once you have identified an error-notification function, the Movie Toolbox calls your function each time the current error value is to be set to a nonzero value. The Movie Toolbox manages the sticky error value. The Movie Toolbox calls your error-notification function only in response to errors generated by the Movie Toolbox.